Challenge: Fixing Structural Issues with Headings and Landmarks
On this page
As seen in a few different tools, the CampSpots site has some issues with its headings and landmarks.
Work through fixing these issues on the Home and About pages, checking with the Web Developer Toolbar and Accessibility Insights as you go.
When you adjust heading levels you’ll usually need to update the styling as well.
When you’re confident in your fixes, run Lighthouse and Axe DevTools again to check your scores.
🛠 Solution: Fixing Headings and Landmarks
There have been quite a few changes made over this workshop module!
Compare your changes to mine in the answer3 directory and watch the videos below as I develop my solutions live.
Changes in the Header & Footer
Inside of includes/header.html we changed the div with an id of “header” to use the semantic <header> element. Do the same thing for the footer— swap out the div with <footer>.
Headers and Footers are special landmarks. When they are top level, i.e. they aren't nested inside of any other landmark areas, they are considered to be global.
Depending on your site's design, there are different options for making things “level-one” or H1 headings.
Inside of the header-logo div, we could wrap the link to make it the H1. Since the header is included on every page, “CampSpots” will always be the top level header.
<!-- inside includes/header.html -->
<header id="header">
<div id="header-nav">
<div id="header-logo">
<h1><a href="/exercise3-extensions" class="header-main-item">
<span class="logo-img">
<img src="/images/icons/camp-spots-logo.svg" alt="" />
</span>
<span class="logo-text">CampSpots</span>
</a></h1>
</div>
<nav id="header-megamenu">
...Adding the H1 around the logo link gives it a huge font size and skews the header size:
Adding styles to includes/_header.scss will fix this:
#header-logo h1 {
font-size: inherit;
margin: 0;
}Always pick the correct heading level for the content within an overall semantic page structure and use CSS to style it.
Changes in the Home Page
The homepage code is located in index.html.
The first thing to change is a div with an id of main. It can swapped out with the semantic <main> element.
Near the tents image is a heading that reminds you that “rest and relaxation is a part of life”. On the starting point of the CampSpots app, this was originally an H3. We could update it to be an H2 since Web Developer Toolbar pointed out the missing heading levels.
Similarly, change the H4 “Places to visit” heading to be an H3.
With CSS classes and the CSS cascade, we can write styles that make our headings look exactly how we want without depending on specific heading levels. For example, utility classes like .heading-primary or .h1-style, .heading-secondary or .h2-style can be added to any heading level to achieve a consistent look and feel with a proper semantic structure. The class names are arbitrary; your team can decide on a naming system.
Changes in the About Page
The first thing here will also be to use the <main> element for the content in about/index.html.
Inside the div with a class of content-block there are several divs that only contain text. These would be better off using the more semantic p tag for paragraphs.
When looking at the existing markup for the contact form area, the “Message” H6 had skipped over heading levels. It also looks like it belongs as a label for the form, so we can change it to the <label> element and fix the form markup in a bit.
Inside of about.scss we can switch the styling that used to be targeted at the H6 instead target the p element. We also need to update the div to point to the address element and take advantage of the CSS cascade to combine the styles. A font-style of normal makes a good addition as well.
About page styling before:
.page-about .form-wrap h6 {
margin-bottom: 0.5em;
}
.page-about .content-block div {
font-size: 1rem;
line-height: 1.5;
margin-bottom: 1em;
}After:
.page-about .content-block p,
.page-about .content-block address {
font-size: 1rem;
font-style: normal;
line-height: 1.5;
margin-bottom: 1em;
}It is generally a good idea to include headings as signposts for each section of the page.
Solution Work and Thought Process
It’s one thing to read code diffs, it’s another to get live commentary during the code writing.
In these workshop videos, I solve the issues that our accessibility tools identified.
Video Transcript
Okay. So let's go make our last couple changes for our extensions. So I'm gonna come back to vs code. We fixed our header for the H one, since we just identified, there's more images in here. Why don't we go fix those real quick? So we've got some SVGs and some decorative images. So I guess, are they decorative?
Let's go look, make our choices. So under plan, your trip, there's two images. So there's an image of a person holding a map and then a motor home. And then next to the text, there's some little icons, I would say maybe the images are somewhat interesting and the icons are pretty decorative, cuz they're just sort of, the icon is like decoration next to the link text.
So perhaps on the icons, I could say alt equals equal equals empty quotes. And I'll do that on both of these alt equals empty quotes. And then for the driving map, we could say what would we say, driving, checking our, checking the route with a map or maybe something trying to reference like the item that it's next to.
So like finding a camp spot on the map, maybe I'll write that for now finding a camp spot on the map. So one thing I'm not doing is writing photo of. Or image of, so when this, this tag, this image tag, when that gets announced in a screen reader, it will already announce the type of thing. So image is already included.
If I were to write photo of in the alt text, it would be kind of repetitive because we already know it's an image. So that's something I'm specifically not including in my alt text and I'm writing it to try and add some, like, if I'm gonna make, make it not decorative, I want to add some content to the page.
That makes sense. So for this one we could say, is that a class C motor home? So kind of fun trivia effect. My first job was washing motor homes. But sometimes I can't remember what type, what types were, what, and it's, I guess it's not that important. I could just say a motor home parked at an RV park at night.
Maybe it's got some lights on, we can make, we can make it say whatever we want. So how about alt a motor home parked at an RV park at night? Okay. You know, made that choice under an RV park. So we fixed that alt text.
Video Transcript
So let's go back to the browser to make some decisions here.
So for landmarks, the goal with those is to add kind of sign posts for the major sections of content. But we can make some quick wins on our landmarks for this page that will set us up for later sections.
So our header, we actually already have some landmark elements in place. So with HTML five, we got elements like nav. There's others we could add, like, so we've got these three main areas and to satisfy what acts was telling us about that we needed content to be wrapped in landmarks. All three of these top level elements would be great candidates for using landmark elements.
So we've got the header element, the main element and the footer element, respectively, that seems pretty straightforward. Let's go and make those changes. So in vs code, I could collapse this to make it easy to see. So for header, it has an ID of header. I'm gonna leave that ID in place, cuz it's matching some of our CSS right now.
In, you know, theoretically if I had more time that I wanted to devote to this task when I'm changing out or if I'm building from scratch. I could write my CSS to hinge off of this header element. There's some differences with types of header elements depending on if they're nested inside of other landmarks or not.
This one is our banner header, so it's kind of our main global header. So I'm gonna leave that ID attribute in place so that my CSS will match this particular header. But just know you can use more semantic element references in your CSS too. So that's really a cool way to go. So I'll hit save here.
We've got our footer as well. So footer, which is also known as the content info when it's this top level landmark. So we've got header footer, and then our index page and any element or sorry, any index HTML file that includes this div ID domain. So we have quite a few of them. There's our about page.
What else do we have within plan your trip? I mean, pretty much all of these pages. I'm not gonna make all these changes right now, but the HTML Lang that we made up here that and changing D I ID main into a main element. Those are changes we could make on pretty much every page. So I changed the opening tag and it sort of expanded all of the contents now.
So if you kinda lose track of where the closing tag is in vias code, there is this line here that I can follow all the way down. I, it, I do need to be able to see the screen, but I can scroll down here and see that since everything was nicely formatted and indented, I can find the closing tag. So sometimes when I'm migrating code and trying to make changes, I can get completely lost.
the indentation. I mean, that's why I'm so particular about getting my indentation and formatting, right, is because trying to find opening and closing tags sometimes can be kind of hard. So this little line can be helpful. So that will show me the opening and closing tags.
Video Transcript
So now let's go back to the browser will hit refresh and those HTML elements, because our CSS was written the way it was.
We should be able to swap out tags pretty seamlessly and have no, no visible changes. I can open up the dev tools with command option. I it's control option or control, shift I on windows, if you're on windows. So let's go back to acts dev tools, run this again, see what we've got. So we've got a heading order issue.
We haven't fixed yet. Probably leave that one alone for the moment, but all of our landmark issues are gone. I can open up the menu again and let's run this again. We fix all those issues. So our menus all good. There's no images in the other sections either. So it was just this one. so I think we're in pretty good shape.
We have one heading issue we could fix, we could double check these color issues. So login don't really know why X is having a problem there, but it's this isn't an issue. It's black text on a white background, so it's unclear what's going on there. The second one is a label I could hit, highlight and scroll down.
I don't really know why that one's having an issue either. But it's white text and a background or black text and a white background. Again, it's got some overlapping, I think it might be because this form is actually kind of, it has a negative margin. So it overlaps a background image above, but it's missing this background.
Color is white somehow. So X the algorithm is it has issues with the stuff sometimes. Same with the dates. This text is fine from a con color contrast perspective. There's also this places to visit. We saw that one already. It's it's probably because of this little corner overlap right here, but I think that one's fine.
So that was for, I was four needs review items as we call 'em.
Video Transcript
So I'm gonna call this good for one last piece before we move on, I wanna go back to lighthouse. Let's run this report again. See what our score is. Now, one thing about lighthouse that I don't love is that it gives you this, you know, trying to add up to a hundred percent thing.
That's a little bit misleading because you know, lighthouse and acts can only find so much automated. And they do tell you that, but I'll think a lot of teams might be like, all right, it's green, it's a hundred. We're good. And then they leave it at that and don't look any deeper. And there could be issues like our whole mega menu functionality wouldn't have.
They wouldn't have caught that. So the number like a hundred percent thing is a little bit could be misleading, but we took it from six. What? 65 or something to 98. That's pretty awesome. we have one heading order issue we could address, but that's such an improvement. I mean, we made some serious changes.
And, you know, didn't really take us too long either. I
Video Transcript
So how about maybe we, we go and change this heading order thing to just really nail it. So this H three and we saw this with our document outline from the web developer extension that it jumped from each one to each three.
So this should probably be an H two maybe. And then this, that would affect the heading under it. Right? So places to visit looking at the style of it, I'm gonna scroll down, we'll close lighthouse for a second. So this is currently marked up as an H three and then this is an H four. So looking at kind of the content structure we could make this in H two so that it, it follows kind of the page structure in a more hierarchical, hierarchical manner.
And then whether to make this places to visit in each, it is currently in H four, but at least follow the heading above it to make it in each three. But I guess content wise, I mean, should it be an H three or an H two? It's pretty subjective. We at least want the kind of overall page content structure to follow some sort of an order.
That's not as tied to style, but whether, yeah, whether we wanna break this out to an H two, gosh, it's kind of a hard decision. I am just going to make the choice to make this a group. So this section will make this an H two, make this an H three and by golly, we are gonna get to a hundred percent okay. So H three let's change this to H two.
And I just did that little trick with command D to select the opening and closing tags. So now this is jumping from H two to age four. That means I need to change this at least to H three, to make it follow for this section. I could also, you know, if I'm really feeling up for it, I could change these to paragraphs.
There might be some style changes that have to be made. And so I'll guess I'll see what happens, but let's go look at the style. Let's see what happened, cuz this is often why teams are making these choices of choosing the wrong heading level or the wrong element is because of the style. So let's go look at what happened.
So this is the way it looks. Now we've got this, you know, font style, font, sizes, font boldness. If I hit refresh. The headings did change a little bit. They look bigger. Our paragraph text looks mostly the same, so that's cool. But our headings now don't match necessarily the, the design artifact that my designer gave me when I built this.
And so they might have words, they might be like, why doesn't that heading look the way it's supposed to or something. And you might be like, cuz I had to change the heading level. Well, if we need to change the style, something I would recommend is creating some utility classes in CSS. So you can choose the right heading level and style it.
However you want. We happen to have some of those classes already. So I'm gonna go to vs code and show them to you. So those let's go see where they live. They are under our CSS.
I'm gonna close some of these files make our content easier to see. So within our SCSS headings are probably under default. Yes, that was good guess. Okay. So these CSS classes already exist. So for each three and up, I guess age three, age four H five, which kind of within the flexibility of the content in those heading levels, those are most commonly the ones where you might need to change the heading level to follow the structure.
Style wise, you know, you need to style it a certain way. So making it look more like an age four or making it look more like an age three. And so having these utility classes is really helpful so that you can pick the right semantic element and style it however you want, or however you need to, to kind of match whatever design you know, there's just design aesthetic reasons why your teammates, you know, might recommend making it look a certain way.
And if that's fine for user experience, we can kind of marry, you know, the underlying accessibility information with some of these design aesthetics. So I've chosen CSS classes of H three dash style H four dash style. You might have other naming conventions like tertiary for H three or quad . They can get a little bit I don't know.
It's like too fancy. So I like the simple names. But you might have other ways of naming these or other mechanisms, other frameworks and things. Really the idea is just to have some CSS class that you can reference to apply the style independently of the element tag name. So under index. I wanna make this look like an H three, I could say class equals H three style.
And on this age, H three was an H four. I could say class equals age four style. And I guess, you know, you could argue it's a bit of a code smell in that we have designed something where the style and the, the heading level doesn't match. You can really open up that conversation with your team if you want.
Sometimes, you know, we don't have unlimited time and we need to make, we need to work within our teams. And that might be a battle that we don't pick we don't wanna wage that battle. And so just having the option of having CSS to style things, it can really come in handy when you just need to get the job done and make the underlying structure accessible.
So I'm gonna come back here, hit refresh, and that reset our font sizes back to the way they were.
Video Transcript
let's open up lighthouse again, we're gonna get it to a hundred percent. Dang it. I think that was the only thing that it found. So lighthouse was not finding those needs review items with the color contrast.
They just, they filter 'em out. It doesn't have that kind of needs review interface. So voila, we went from 60 some percent up to a hundred. And so that's pretty awesome. I'm very happy with that. Even though there could be more, you know, there's always more that we could be checking especially interactive functionality wise, cuz I would say that's the big shortcoming of a lot of these tools is that they're not gonna go through and try to interact with the keyboard and tell you what's wrong, functionally.
That way. That's something that you have to go and test yourself. Writing automation tests for it as we'll do next week. That that's a lot in that realm, but we found a lot of cool stuff using tooling. We've gone from something that was kind of pathetic. I mean, being in the sixties for our score, like that's sadly common, but we can do so much better and we did, we got it to a hundred.
So I think, yeah, we should feel proud that we've done all of that today. That's pretty awesome.